18장 실제 기능 만들어 보기 (입문판)
원서: 클로드 코드 완벽 가이드, 코드팩토리 최지호
이 장에서 딱 7가지만 가져가세요. 1. MVP — 기능 욕심을 줄이고 "핵심만 먼저" 만드는 법 2. 플래닝 모드 — Shift+Tab 두 번으로 "설계도 먼저" 그리는 법 3. 멀티에이전트 — 터미널 여러 개로 "동시에 일 시키는" 법 4. 커스텀 커맨드 — 자주 쓰는 프롬프트를 "버튼처럼" 저장하는 법 5. 워크트리 매크로 — 작업실을 여러 개 "한 줄로 여는" 법 6. 이슈→워크트리→PR 흐름 — 하나의 기능을 "안전하게 합치는" 법 7. 동시 실행 — 독립된 두 일을 "충돌 없이 같이" 하는 법
개념 하나에 섹션 하나입니다. 천천히 따라오면 됩니다.
이 장을 다 읽으면 이렇게 됩니다. - MVP가 무엇이고 왜 먼저 만드는지 설명한다. - 순차 작업과 병렬 작업을 구분한다. - 플래닝 모드로 계획을 세우고, 커스텀 커맨드와 워크트리로 실제 기능을 따라 만든다.
이 장은 앞에서 배운 클로드 코드 기본 사용법, 플래닝 모드, CLAUDE.md를 실제 프로젝트에 묶어서 써 봅니다. 앞 장에서 하나씩 배운 도구들을 "진짜 서비스 하나 만들기"에 합쳐 보는 장이라고 생각하면 됩니다.
18-1 MVP 기능 정의하기
이런 적 있죠?
새 앱을 만든다고 마음먹으면 욕심이 납니다. "로그인도 넣고, 채팅도 넣고, 결제도 넣고, 알림도 넣고..." 그러다 6개월이 지나도 출시를 못 합니다. 정작 손님이 진짜 원하는 게 뭔지도 모른 채요.
이렇게 "다 넣으려다 아무것도 못 내는" 일을 막아 주는 게 MVP입니다.
그게 바로 MVP
MVP는 "핵심 가치만 담은 최소한의 제품"이라는 뜻입니다. (MVP = 손님 반응을 보려고 딱 필요한 만큼만 만든 첫 버전. 식당 오픈할 때 대표 메뉴 3개만 먼저 내는 것과 같습니다.)
판단 기준은 딱 한 문장입니다. "이 기능이 없으면 이 서비스가 성립할 수 있을까?" 없어도 되면 빼고, 없으면 서비스 자체가 안 되는 것만 남깁니다.
비유로 먼저
식당을 새로 연다고 해 봅시다.
| 비유 | 클로드 코드에서 | 주의 |
|---|---|---|
| 메뉴 100개를 한 번에 준비 | 기능을 한꺼번에 다 구현 | 시간·비용 폭발, 손님이 뭘 좋아하는지 모름 |
| 대표 메뉴 3개만 먼저 오픈 | 핵심 기능만 먼저 만들어 배포 | 빠르게 반응 확인 후 인기 메뉴(기능) 확장 |
| 손님 줄 서는 메뉴를 늘림 | 반응 좋은 기능을 추가 개발 | 안 되는 기능에 시간 안 버림 |
MVP를 정하는 3단계
1단계. 개선점 목록 작성 지금 사이트에서 고쳐야 할 점을 구체적으로 적습니다. 예를 들면 이렇게요. - 불필요한 페이지 삭제 - 별점 -> 좋아요/싫어요로 변경 - 필터 다시 설계 (예산, 지역, 환경, 계절) - 카드 구조 변경 (이름:값 형태로 표시)
2단계. 클로드 코드에게 계획 요청 새 대화창을 열고 개선점을 전달합니다. 그리고 "Phase별 실행 계획을 세워 줘"라고 부탁합니다. (Phase = 따로따로 끝낼 수 있게 잘라 놓은 작업 묶음. 이사할 때 "방→주방→거실" 순서로 나누는 것과 같습니다.)
3단계. 계획 검토 후 SPEC.md에 저장 클로드 코드가 만든 계획을 마크다운 파일로 저장합니다. (SPEC.md = 무엇을 어떻게 만들지 적어 둔 명세 파일. "공사 계획서"라고 보면 됩니다.) 각 항목을 체크박스로 적어 두면 진행 상황을 한눈에 봅니다.
실제 예 — K-NOMAD HUB 개선점 목록
원서에서는 "K-NOMAD HUB"라는 예제 사이트를 개선합니다. 정리하면 이렇게 적습니다.
삭제할 것 - 홈페이지/인증 외 불필요 페이지 전부 삭제 - 별점 평점 삭제 - 프로필 버튼 빼고 내비게이션 버튼 삭제 - '자세히 보기' 버튼 삭제
추가/변경할 것 - [좋아요] [싫어요] 버튼 구현 - 필터: 예산(100만원/100~200/200만원), 지역(수도권/경상도 등), 환경(자연친화/도심선호 등), 최고 계절(봄/여름/가을/겨울) - 카드에 필터 정보를 이름:값 형태로 표시 - 가짜 데이터 수정 (도시별 필터 요소 추가) - 'TOP 추천 도시' -> '도시 리스트'로 변경
Phase별 계획은 이런 모습
Phase 1: 코어 구조 정리 및 내비게이션 단순화
- /cities, /compare, /community, /guides 페이지 삭제
- Header.tsx 내비게이션 정리
Phase 2: 평점 시스템 개선 (별점 -> 좋아요/싫어요)
- CityCard 컴포넌트 수정
- 상태 관리 로직 구현
Phase 3~6: 필터, 카드 구조, 데이터, 제목 변경 등
잘못된 예 vs 올바른 예
잘못된 예 "별점, 채팅, 결제, 알림, 다국어, 다크모드 다 한 번에 만들어 줘." -> 끝이 안 보이고, 뭐가 핵심인지도 흐려집니다.
올바른 예 "좋아요/싫어요 버튼이 없으면 이 사이트가 성립이 안 돼. 그것부터 Phase 1로 만들자." -> 핵심만 먼저, 나머지는 나중에.
이럴 때 이렇게: 기능 아이디어가 10개 떠오르면, 각 기능에 "이거 없으면 서비스가 안 되나?"를 물어보세요. "아니오"인 건 일단 목록 아래로 내립니다.
한 걸음 더 ▸ SPEC.md를 쓰는 이유
머릿속 계획은 대화가 길어지면 흐려집니다. SPEC.md처럼 파일로 적어 두면 클로드 코드가 그 파일을 다시 읽어 "지금 어디까지 했지?"를 기억합니다. 계획을 파일로 박아 두는 것 자체가 일종의 메모리인 셈입니다.
18-2 MVP 기능 구현하기
이런 적 있죠?
설계도 없이 집을 짓기 시작했다고 해 봅시다. 기둥 위치가 엉뚱하고, 배관이 부딪치고, 결국 전체를 다시 짓습니다. 코드도 똑같습니다. 계획 없이 "일단 만들어 줘" 하면, 만들다가 구조가 꼬여서 다 갈아엎게 됩니다.
이걸 막아 주는 게 플래닝 모드입니다.
그게 바로 플래닝 모드
플래닝 모드는 클로드 코드가 "바로 코드를 고치지 않고, 어떻게 할지 계획부터 보여 주는" 모드입니다. (플래닝 모드 = 실행 전 설계도부터 그리는 상태. 요리 전에 레시피를 먼저 확인하는 것과 같습니다.)
들어가는 법은 간단합니다. Shift+Tab을 두 번 누릅니다.
비유로 먼저
| 비유 | 클로드 코드에서 | 주의 |
|---|---|---|
| 설계도 없이 바로 건축 | 계획 없이 바로 코드 수정 | 구조 꼬이면 전체 재시공 |
| 설계도 먼저 완성 후 공사 | 플래닝 모드로 계획 먼저 | 계획 확인 후 실행하면 안전 |
| 1층 완성→검수→2층 | Phase 1 완성→검수→Phase 2 | 단계마다 확인하며 진행 |
플래닝 모드 따라 하기
1단계. Shift+Tab 두 번 -> 플래닝 모드 진입 그리고 이렇게 요청합니다.
@SPEC.md 파일의 Phase 1을 어떻게 구현할지 계획해 줘.
작업 끝나면 lint와 typecheck를 실행해서 문제를 해결해 줘.
(lint = 코드 스타일과 잠재적 오류를 자동으로 잡아 주는 검사기. 맞춤법 검사기와 비슷합니다.) (typecheck = 변수에 들어갈 값의 종류가 맞는지 확인하는 검사. "숫자 칸에 글자 넣었네?"를 잡아 줍니다.)
2단계. 클로드 코드가 상세 실행 계획을 만듦 보통 이런 항목으로 나옵니다. - Tasks to Complete (할 일 목록) - Verification Steps (확인 방법) - Expected Outcome (예상 결과)
3단계. 계획 확인 후 실행 계획이 괜찮으면 진행시킵니다. 그러면 Todo 리스트가 자동으로 만들어지고, 하나씩 체크하며 진행합니다. (Todo 리스트 = 할 일을 체크박스로 적어 두고 끝낸 것에 표시하는 목록. 장보기 메모와 같습니다.)
실제 예 — Phase 1 실행 결과
Phase 1 Implementation Plan: Core Structure Cleanup
Tasks to Complete:
1. Delete Page Directories
- /src/app/cities/ 삭제
- /src/app/compare/ 삭제
- /src/app/community/ 삭제
- /src/app/guides/ 삭제
2. Update Header Navigation
- 삭제된 페이지의 메뉴 항목 제거
- 인증 관련 요소만 유지
3. Verification Steps
- 홈페이지(/) 정상 로드 확인 (HTTP 200)
- 삭제된 페이지 404 반환 확인
모델은 작업 난이도에 맞게 고르기
클로드 코드는 여러 모델을 골라 쓸 수 있습니다. 원서에서는 두 가지를 기준으로 설명합니다.
- 난이도 낮은 작업 (단순 삭제·정리 같은 Phase 1) -> Sonnet 모델. 빠르고 저렴합니다.
- 난이도 높은 작업 (복잡한 로직 구현) -> Opus 모델. 더 깊이 추론합니다.
핵심은 이겁니다. Sonnet으로도 충분한 일을 굳이 Opus에게 시키지 마세요. 난이도에 맞게 고르면 시간과 비용을 크게 아낄 수 있습니다.
모델 이름(Sonnet, Opus 등)과 그 특성은 원서/노트 기준 예시이며, 최신 모델 구성과 사용 가능 여부는 공식 문서(https://docs.claude.com)에서 확인하세요.
CLAUDE.md에 반복 규칙을 박아 두기
매번 프롬프트 끝에 "lint랑 typecheck도 돌려 줘"를 적기는 귀찮습니다. 그럴 땐 CLAUDE.md에 한 번 적어 두면 됩니다. (CLAUDE.md = 클로드 코드에게 항상 지키라고 알려 주는 규칙 파일. 알바생에게 주는 근무 수칙과 같습니다. 앞 장에서 다룬 그 파일입니다.)
이런 내용을 적어 두면 좋습니다.
각 단계 구현이 끝날 때마다 lint와 typecheck를 실행해서
문제가 없는지 확인하고, 있으면 해결해 줘.
끝낸 작업은 체크박스에 체크해 줘.
이렇게 해 두면 매번 똑같은 말을 반복할 필요가 없습니다.
잘못된 예 vs 올바른 예
잘못된 예 계획도 안 보고 "Phase 전체를 한 번에 다 만들어 줘." -> 중간 점검 없이 쭉 가다가, 1단계에서 어긋난 게 6단계까지 번집니다.
올바른 예 플래닝 모드로 계획을 본 뒤 "Phase 1만 먼저 해 줘. 끝나면 lint·typecheck 돌려 줘." -> 한 단계 끝낼 때마다 멀쩡한지 확인하고 다음으로 갑니다.
이럴 때 이렇게: 에러가 나면 당황하지 말고 에러 로그를 그대로 복사해서 클로드 코드에 붙여넣으세요. 클로드 코드가 로그를 읽고 원인을 짚어 줍니다.
한 걸음 더 ▸ 너무 세세한 플래닝은 역효과
계획을 너무 잘게 쪼개 놓으면, 몇 단계 지난 뒤의 상황과 처음 계획이 안 맞아 문맥이 끊깁니다. 작업을 실행할 땐 지금 에이전트가 처한 상황을 전체적으로 파악하게 하는 편이 낫습니다. "적당히 큰 단위로 나누기"가 핵심입니다.
18-3 멀티에이전트 작업 준비하기
이런 적 있죠?
혼자 일하는 셰프는 재료 손질 끝나야 조리하고, 조리 끝나야 플레이팅합니다. 순서대로 하니 느립니다. 손님이 몰리면 주방이 막힙니다.
클로드 코드도 터미널 하나로만 쓰면 한 번에 한 가지 일밖에 못 시킵니다. 이걸 풀어 주는 게 멀티에이전트입니다.
그게 바로 멀티에이전트
멀티에이전트는 "터미널을 여러 개 열어 클로드 코드를 동시에 여러 마리 굴리는" 방식입니다. (멀티에이전트 = 같은 일꾼을 여러 명 동시에 쓰는 것. 주방에 셰프 3명을 두는 것과 같습니다.)
비유로 먼저
| 비유 | 클로드 코드에서 | 주의 |
|---|---|---|
| 1인 셰프가 순서대로 조리 | 터미널 1개로 하나씩 작업 | 느림, 한 번에 하나만 |
| 셰프 여럿이 동시에 다른 요리 | 터미널 여럿으로 다른 기능 동시 작업 | 빠름, 단 검수 부담 커짐 |
| 검수 몰려 대충 맛 보기 | 결과를 대충 확인하고 넘김 | 가장 경계할 함정! |
우리의 역할은 코딩이 아니라 플래닝
여기서 역할이 바뀝니다.
- 에이전트 = 직접 코드를 짜는 주니어 개발자
- 우리 = 숲 전체를 보는 시니어 개발자 / 기획자
그래서 우리가 지킬 원칙은 이렇습니다. 1. 계획을 충분히 작고, 상세하고, 세밀하게 세운다. 2. 클로드 코드가 코드를 짜는 동안, 우리는 다음 작업을 플래닝한다. 3. 검수가 한꺼번에 몰려도 대충 넘기지 않는다. 4. 초반에는 의도를 넘어서는 과한 설계를 경계한다. 5. 내가 의도한 기능만 만들어졌는지 꼭 확인한다.
잘못된 예 vs 올바른 예
잘못된 예 터미널 3개에 일을 시켜 놓고, 셋 다 끝나자 결과를 대충 훑고 다 합칩니다. -> 검수가 몰리면 사람은 본능적으로 대충 보게 됩니다. 버그가 그대로 들어갑니다.
올바른 예 터미널 2개만 돌리고, 하나 끝날 때마다 제대로 확인하고 합칩니다. -> 내가 감당할 수 있는 만큼만 동시에 굴립니다.
이럴 때 이렇게: 프로젝트가 커질수록 환각(없는 사실을 그럴듯하게 지어내는 현상)이 늘어납니다. 그러니 동시에 굴리는 개수를 늘리기 전에, "내가 결과를 다 검증할 수 있나?"를 먼저 자문하세요.
한 걸음 더 ▸ 멀티에이전트가 어울리는 작업
아무 일이나 동시에 돌리는 게 아닙니다. 병목이 되는 일(초기 핵심 기능, 데이터베이스 작업, 치명적 버그 수정)을 두 개 이상 터미널로 동시에 푸는 게 효과적입니다. 서로 영향이 적은 독립된 일일수록 동시 작업에 잘 맞습니다.
18-4 필수 커스텀 커맨드 생성하기
이런 적 있죠?
같은 부탁을 매번 처음부터 길게 타이핑한 적 있죠? "기능을 작은 작업으로 나눠 주고, 우선순위 매기고, 예상 시간도 적고, 의존성도..." 매번 조금씩 다르게 적으니 결과도 매번 달라집니다.
이걸 한 방에 해결하는 게 커스텀 커맨드입니다.
그게 바로 커스텀 커맨드
커스텀 커맨드는 "자주 쓰는 긴 프롬프트를 파일로 저장해 두고, 짧은 명령 한 줄로 부르는" 기능입니다. (커스텀 커맨드 = 내가 만든 단축 명령. 문자 보낼 때 저장해 둔 자주 쓰는 문구를 불러오는 것과 같습니다.)
저장 위치는 정해져 있습니다.
.claude/commands/ 폴더에 마크다운(.md) 파일로 둡니다.
그 안에서 $ARGUMENT라고 적은 자리에 내가 입력한 값이 들어갑니다.
($ARGUMENT = 사용자가 넣는 값이 대신 들어가는 빈칸. 양식의 "이름: ___" 빈칸과 같습니다.)
비유로 먼저
| 비유 | 클로드 코드에서 | 주의 |
|---|---|---|
| 매번 긴 문자 새로 작성 | 매번 긴 프롬프트 새로 입력 | 시간 낭비, 결과 들쭉날쭉 |
| 자주 쓰는 문구 저장 | .claude/commands/에 커맨드 저장 |
짧은 한 줄로 호출 |
| 양식의 빈칸 채우기 | $ARGUMENT에 입력값 대입 |
같은 양식으로 일관된 결과 |
커맨드 (1) feature-breakdown
파일 위치: .claude/commands/feature-breakdown.md
하는 일: 만들고 싶은 기능을 입력하면, 작은 작업 단위로 쪼갠 실행 계획을 만들어 줍니다.
대략 이런 구조로 결과가 나옵니다. 1. 기능 분석 — 핵심 목표, 범위, 사용 케이스 2. 아키텍처 분해 — 프런트엔드/백엔드/외부 연동 3. 작업 분해 — [우선순위] 작업명, 설명, 예상 시간, 의존성, 완료 조건 4. 의존성 관계 — 병렬 가능 / 순차 필요 / 블로커 5. 검증 계획 — 단위·통합·사용성 테스트 6. 진행 추적 — 마일스톤, 리스크, 롤백 계획 7. 배포 전략 — 스테이징 검증, 점진적 배포, 모니터링
(블로커 = 다른 일을 시작하려면 먼저 끝나 있어야 하는 선행 작업. 라면 끓이기 전에 "물 끓이기"가 블로커입니다.)
사용 예
/feature-breakdown 도시 상세페이지를 만들고 싶어
커맨드 (2) create-issue
파일 위치: .claude/commands/create-issue.md
하는 일: 내가 적은 내용을 깃허브 이슈로 만들어 줍니다.
(이슈 = 할 일이나 버그를 깃허브에 등록해 두는 메모 카드. 포스트잇을 보드에 붙이는 것과 같습니다.)
작업 지침은 이렇게 짜 둡니다.
1. 요청 분석 — 작업 유형과 우선순위 결정
2. 라벨링 적용 (CLAUDE.md 참조) — 유형(feature, refactor, ui/ux 등), 우선순위(high/medium/low), 상태(idea)
3. 이슈 내용 — 명확한 제목, 상세 설명, 라벨, 완료 조건
4. 마크다운 형식으로 전문적으로 작성
5. gh issue create 명령으로 저장소에 이슈 생성
(gh = 깃허브를 터미널에서 다루는 공식 명령 도구. 깃허브 사이트를 안 켜고도 이슈를 만들 수 있게 해 줍니다.)
사용 예
/create-issue 지금까지 세운 계획을 깃허브 이슈로 생성해 줘
커맨드 (3) resolve-issue
파일 위치: .claude/commands/resolve-issue.md
하는 일: 이슈 번호를 주면 그 이슈를 분석하고, 구현 계획을 세운 뒤, 사용자 검토를 받고 진행합니다.
절차는 이렇습니다.
1. 이슈 정보 가져오기 — gh issue view {이슈번호}
2. 이슈 분석 — 요구사항, 관련 파일, 기술적 고려사항
3. 구현 계획 — 작업 분해, 예상 시간, 파일 변경, 테스트 계획
4. 사용자 검토 요청 — 계획이 적절한지, 빠진 건 없는지 확인
핵심은 "계획을 먼저 세우고, 사용자 승인을 받은 뒤에만 구현한다"입니다.
사용 예
/resolve-issue 1
실제 예 — feature-breakdown 실행 결과
/feature-breakdown 도시 카드를 눌렀을 때 이동할 상세페이지를 제작하고 싶어
결과 요약:
1. 기능 분석 — 핵심 목표: 카드 클릭 -> 상세 페이지 이동
2. 아키텍처 분해 — 프런트: /cities/[id]/page.tsx, 백엔드: cities.json 활용
3. 작업 분해 — [HIGH] 동적 라우팅 페이지 생성 (2시간) 등
4. 의존성 — 순차: 동적 라우트 -> 데이터 로딩 -> 카드 링크
병렬: 이미지 갤러리 <-> 점수 시각화
블로커: 동적 라우트가 모든 작업의 전제
잘못된 예 vs 올바른 예
잘못된 예 커맨드 결과가 마음에 안 들어서, 나온 텍스트를 손으로 직접 고칩니다. -> 다음에 또 쓰면 똑같이 안 좋은 결과가 나옵니다.
올바른 예
결과가 별로면 .claude/commands/feature-breakdown.md 파일 자체를 고칩니다.
-> 다음부터 모든 결과가 좋아집니다.
이럴 때 이렇게: 같은 종류의 부탁을 두 번 이상 했다면, 그건 커스텀 커맨드로 만들 신호입니다. 프로젝트가 길어질수록 이렇게 쌓인 커맨드가 효율을 크게 올려 줍니다.
한 걸음 더 ▸ 출력이 아니라 커맨드를 고친다
커스텀 커맨드의 핵심 사고방식은 "결과물을 고치지 말고 틀(커맨드)을 고친다"입니다. 틀을 한 번 다듬으면 그 틀로 만드는 모든 결과가 같이 좋아집니다. 이게 프로젝트가 진행될수록 클로드 코드가 "최적화되는" 원리입니다.
18-5 워크트리 매크로 제작하기
이런 적 있죠?
작업실 하나에서 그림도 그리고 목공도 한다고 해 봅시다. 그림 그리다 목공하려면 그림 도구를 다 치우고 목공 도구를 꺼내야 합니다. 다시 그림 그리려면 또 바꿔야 하고요. 이 "왔다 갔다"가 시간을 잡아먹습니다.
코드에서 브랜치를 바꿀 때마다 이런 일이 벌어집니다. 이걸 없애 주는 게 워크트리입니다.
그게 바로 워크트리
워크트리는 "하나의 저장소에서 여러 브랜치를 각각 다른 폴더에 동시에 펼쳐 두는" 깃 기능입니다. (워크트리 = 같은 프로젝트의 작업실을 여러 개 만드는 것. 브랜치마다 전용 책상을 따로 두는 것과 같습니다.) (브랜치 = 원본을 건드리지 않고 따로 떼어 작업하는 복사 줄기. 책의 "초안 버전"과 같습니다.)
비유로 먼저
| 비유 | 클로드 코드에서 | 주의 |
|---|---|---|
| 작업실 1개에서 도구 바꿔 끼우기 | 브랜치 전환마다 컨텍스트 스위칭 | 매번 바꾸는 비용 발생 |
| 작업실 여러 개에 도구 그대로 | 브랜치마다 폴더 따로 펼침 | 동시에 다른 작업 가능 |
| 작업실에 이름표 붙이기 | 워크트리 이름에 이슈 번호 | 작업 추적이 쉬움 |
create-worktree.sh 만들기
매번 "워크트리 만들고 -> 그 폴더로 이동 -> 클로드 코드 실행"을 손으로 하면 번거롭습니다. 이걸 한 줄로 묶는 셸 스크립트를 만듭니다. (셸 스크립트 = 여러 터미널 명령을 한 파일에 적어 한 번에 실행하는 자동화 메모. 매크로와 같습니다.)
#!/bin/bash
# 워크트리 이름을 인수로 받아 생성하고 이동
if [ $# -eq 0 ]; then
echo "Error: 워크트리 이름을 입력해 주세요!"
return 1
fi
ARGUMENT=$1
WORKTREE_PATH="../worktree/$ARGUMENT"
if git worktree add "$WORKTREE_PATH"; then
echo "워크트리 생성 성공: $WORKTREE_PATH"
cd "$WORKTREE_PATH" || return 1
echo "디렉터리 변경 완료 $(pwd)"
claude # 워크트리에서 클로드 코드 실행
else
echo "워크트리 생성에 실패했습니다."
return 1
fi
실행은 반드시 점(.)을 붙여서
이 스크립트는 실행 방법이 중요합니다.
올바른 실행
. ./create-worktree frontend
. ./create-worktree issue-82
잘못된 실행
./create-worktree frontend
왜 그럴까요?
점(.) 없이 실행하면 스크립트가 별도의 서브셸에서 돕니다.
그 안에서 cd로 폴더를 바꿔도 내가 보던 터미널의 위치는 그대로입니다.
점(.)이나 source를 붙이면 지금 이 터미널에서 직접 실행되어, cd로 옮긴 폴더가 그대로 유지됩니다.
(서브셸 = 잠깐 켰다 꺼지는 별도의 터미널 방. 그 방에서 한 일은 방을 나가면 사라집니다.)
워크트리 쓸 때 주의 2가지
-
커밋 먼저 하기 워크트리를 만들기 전에, 지금 작업을 반드시 커밋하세요. 커밋 안 한 코드는 새 워크트리로 복사되지 않습니다. (커밋 = 지금까지의 변경을 저장하고 기록으로 남기는 것. 게임의 "저장하기"와 같습니다.)
-
이름에 이슈 번호 쓰기
. ./create-worktree issue-1
이렇게 하면 작업 이름이 겹치지 않고 추적도 쉽습니다.
잘못된 예 vs 올바른 예
잘못된 예
커밋도 안 하고 . ./create-worktree issue-1 실행.
-> 방금까지 짠 코드가 새 워크트리에 안 보여서 당황합니다.
올바른 예
"지금까지 작업 커밋해 줘" -> 그다음 . ./create-worktree issue-1.
-> 작업이 새 워크트리에도 그대로 들어 있습니다.
이럴 때 이렇게: 워크트리는 ../worktree/이름 폴더에 생깁니다. 그 폴더로 들어가서 서버를 실행하면, 그 브랜치만의 결과를 따로 확인할 수 있습니다.
한 걸음 더 ▸ 워크트리는 브랜치를 만드는 개념
워크트리는 단순히 폴더를 복사하는 게 아니라, 새 브랜치를 떼어 그 폴더에 펼치는 것입니다. 그래서 워크트리 폴더에서 한 작업은 그 브랜치에만 쌓입니다. 원본(메인 브랜치)은 그대로 보존되니, 마음 놓고 실험할 수 있습니다.
18-6 상세페이지 작업하며 동시에 플래닝하기
이런 적 있죠?
택배를 아무 검수 없이 바로 고객에게 던지면 어떻게 될까요? 포장이 터졌거나 물건이 잘못 들어가도 그대로 나갑니다. 코드도 검수 없이 메인에 바로 합치면, 깨진 코드가 그대로 배포됩니다.
그래서 "주문 -> 포장 -> 검수 -> 출고" 같은 안전한 흐름이 필요합니다.
그게 바로 이슈 기반 워크플로우
지금까지 배운 도구(커스텀 커맨드, 워크트리)를 하나의 흐름으로 엮습니다. "이슈 만들기 -> 워크트리 만들기 -> 구현 -> 커밋 -> PR -> 머지 -> pull"입니다. (PR = 풀 리퀘스트. 내 브랜치 변경을 메인에 합치기 전에 "이거 합쳐도 될까요?" 검수받는 절차. 보고서 결재 올리는 것과 같습니다.) (머지 = 검수 끝난 변경을 메인 브랜치에 실제로 합치는 것.)
비유로 먼저 — 택배 시스템
| 비유 | 클로드 코드에서 | 주의 |
|---|---|---|
| 주문 접수 | /create-issue로 이슈 생성 |
할 일을 먼저 기록 |
| 포장 라인 배정 | . ./create-worktree issue-1 |
이슈별 전용 작업 공간 |
| 포장 작업 | /resolve-issue 1로 구현 |
계획 확인 후 구현 |
| 품질 검수 | "Pull Request 만들어 줘" | 합치기 전 검수 |
| 출고 | 깃허브에서 Merge | 검수 통과분만 합침 |
| 재고 동기화 | git pull origin main |
메인 최신화 |
전체 흐름 따라 하기
1. 이슈 분해
/feature-breakdown 도시 상세페이지
2. 이슈 생성
/create-issue 지금까지 세운 계획을 이슈로 만들어 줘
-> 깃허브에서 #1 이슈 확인
3. 워크트리 생성
. ./create-worktree issue-1
4. 구현
/resolve-issue 1
-> 계획 확인 후 "구현을 시작해 줘"
5. 커밋
"현재까지 작업 내용을 커밋해 줘"
6. PR 생성
"현재까지 작업을 기반으로 Pull Request를 만들어 줘"
7. 머지
깃허브에서 Merge pull request 클릭
8. 메인 최신화
git pull origin main
실제 예 — 도시 상세페이지 PR
PR: 포괄적인 도시 상세 페이지 및 향상된 UI 컴포넌트 구현 #3
변경 사항:
- 동적 라우팅 포함한 도시 상세 페이지 시스템 구현
- 브레드크럼 내비게이션과 주요 지표가 있는 CityHero 컴포넌트 추가
- 8개 점수 카테고리의 진행률을 보여 주는 CityStats 컴포넌트 생성
- 상세 정보 섹션이 있는 CityDetail 컴포넌트 구축
변경 파일 (8 files, 421 insertions, 3 deletions):
- src/app/cities/[id]/page.tsx (신규)
- src/components/cities/CityDetail.tsx (신규)
- src/components/cities/CityHero.tsx (신규)
- src/components/cities/CityStats.tsx (신규)
- src/components/cities/CityCard.tsx (수정)
잘못된 예 vs 올바른 예
잘못된 예 구현이 끝나자마자 로컬에서 메인에 직접 합칩니다. -> 아무도 검수를 안 했고, 충돌이 나도 모릅니다.
올바른 예 "Pull Request 만들어 줘"로 PR을 올리고, 깃허브에서 변경 내용을 확인한 뒤 Merge합니다. -> 검수 단계를 거치고, 충돌도 깃허브가 잡아 줍니다.
이럴 때 이렇게: /resolve-issue는 곧바로 코드를 짜지 않고 계획부터 보여 줍니다. 그 계획을 읽고 "이대로 구현해 줘"라고 해야 진행됩니다. 한 작업이 구현되는 동안, 우리는 다음 이슈를 플래닝하면 시간이 안 낭비됩니다.
한 걸음 더 ▸ 결과 확인은 워크트리 폴더에서
작업한 결과를 보려면, 메인 폴더가 아니라 그 작업의 워크트리 폴더(../worktree/issue-1)로 들어가 서버를 실행하세요.
그래야 그 브랜치만의 변경 결과를 정확히 봅니다.
18-7 여러 작업 동시에 실행하기
이런 적 있죠?
인테리어 전문가 두 명이 있다고 해 봅시다. 한 명은 거실 커튼을 바꾸고, 다른 한 명은 주방 싱크대를 바꿉니다. 서로 다른 공간이라 동시에 해도 부딪칠 일이 없습니다. 그런데 둘이 같은 벽에 페인트를 칠하면? 칠이 겹쳐 엉망이 됩니다.
코드의 동시 작업도 똑같습니다.
그게 바로 병렬 작업과 컨플릭트
서로 다른 파일을 고치는 독립된 일은 동시에 해도 안전합니다. 같은 파일의 같은 부분을 동시에 고치면 머지 컨플릭트가 납니다. (머지 컨플릭트 = 같은 곳을 둘이 다르게 고쳐 "둘 중 뭘 쓸지" 정해야 하는 충돌 상황. 같은 칸에 두 사람이 다른 답을 적은 것과 같습니다.)
비유로 먼저 — 인테리어 전문가 둘
| 비유 | 클로드 코드에서 | 주의 |
|---|---|---|
| 거실 vs 주방 따로 작업 | 서로 다른 파일 수정 | 충돌 없음, 동시 가능 |
| 같은 벽에 동시 페인트칠 | 같은 파일 같은 부분 수정 | 머지 컨플릭트 발생 |
| 전문가 둘이 각자 공간 | 터미널 둘 + 워크트리 둘 | 브랜치도 따로 |
병렬 작업 따라 하기
먼저 독립적인 이슈 두 개를 미리 만들어 둡니다. - issue-2: [좋아요] 버튼 레이아웃 변경 - issue-3: 필터 Select 최대 너비 변경
그다음 터미널을 두 개 띄웁니다.
[터미널 1]
. ./create-worktree issue-2
/resolve-issue 2
[터미널 2]
. ./create-worktree issue-3
/resolve-issue 3
두 작업이 동시에 진행됩니다. 완료되면 각자 서버를 실행해 따로 검수하고, 각각 PR을 만들어 깃허브에서 머지합니다.
잘못된 예 vs 올바른 예
잘못된 예 두 터미널에 "둘 다 CityCard.tsx의 같은 함수를 고쳐 줘"를 시킵니다. -> 같은 파일 같은 부분이라 합칠 때 머지 컨플릭트가 납니다.
올바른 예 한 터미널은 좋아요 버튼(파일 A), 다른 터미널은 필터 너비(파일 B)처럼 서로 다른 파일을 맡깁니다. -> 영역이 안 겹쳐서 깔끔하게 둘 다 머지됩니다.
이럴 때 이렇게: 동시에 돌릴 이슈를 고를 때는 "이 둘이 같은 파일을 건드리나?"를 먼저 확인하세요. 안 겹치면 동시에, 겹치면 순서대로 하는 게 안전합니다.
한 걸음 더 ▸ 작업 완료 순서는 항상 같다
병렬로 하든 순차로 하든, 한 이슈를 마무리하는 순서는 동일합니다. 구현 -> 검수 -> 커밋 -> PR 생성 -> 깃허브 머지. 이 순서를 지키면, 동시에 여러 개를 굴려도 안전하게 합칠 수 있습니다.
한눈에 보는 비교표
순차 작업 vs 병렬 작업
| 항목 | 순차 (싱글 에이전트) | 병렬 (멀티에이전트) |
|---|---|---|
| 터미널 수 | 1개 | 2개 이상 |
| 작업 방식 | Phase 순서대로 하나씩 | 독립 이슈를 동시에 |
| 속도 | 느림 | 빠름 |
| 컨플릭트 위험 | 없음 | 같은 파일 수정 시 발생 |
| 어울리는 상황 | 의존성 있는 작업 | 독립적인 기능 개발 |
| 검수 부담 | 낮음 | 높음 (대충 검수 경계) |
직접 머지 vs PR을 통한 머지
| 항목 | 직접 머지 | PR을 통한 머지 |
|---|---|---|
| 검수 과정 | 없음 | 깃허브에서 변경 확인 |
| 안전성 | 낮음 | 높음 (충돌 자동 감지) |
| 이력 관리 | 불투명 | PR 단위로 추적 |
| 권장 여부 | 비추천 | 권장 |
커스텀 커맨드 3종
| 항목 | feature-breakdown | create-issue | resolve-issue |
|---|---|---|---|
| 목적 | 기능을 작은 작업으로 분해 | 깃허브 이슈 생성 | 이슈 분석 후 구현 계획 |
| 입력 | 만들고 싶은 기능 | 생성할 이슈 내용 | 깃허브 이슈 번호 |
| 출력 | 7단계 실행 계획 | 깃허브 이슈 | 구현 계획 + 검토 요청 |
| 쓰는 시점 | 기능 기획 단계 | 계획 완료 후 | 구현 시작 전 |
연습문제
Q1. MVP 기능을 정할 때 가장 중요한 판단 기준은?
A. "이 기능 없이 이 서비스가 성립할 수 있을까?"입니다. 핵심 가치를 전달할 최소한의 기능만 고르는 것이 MVP이고, 욕심을 줄여 본질에 집중하는 게 핵심입니다.
Q2. 플래닝 모드에 들어가는 단축키와, 너무 세세한 플래닝이 위험한 이유는?
A. Shift+Tab을 두 번 누릅니다. 너무 잘게 단계를 나누면, 몇 단계 지난 뒤의 상황과 처음 계획이 안 맞아 문맥이 끊깁니다. 그래서 지금 상황을 전체적으로 파악하게 하는 편이 낫습니다.
Q3. 커스텀 커맨드의 $ARGUMENT는 어떤 역할을 하나요?
A. 커맨드 실행 시 사용자가 입력한 값이 대신 들어가는 빈칸입니다.
/feature-breakdown 도시 상세페이지에서 "도시 상세페이지"가$ARGUMENT에 대입됩니다. 덕분에 하나의 틀로 다양한 입력에 같은 형식의 결과를 만들 수 있습니다.
Q4. 워크트리 스크립트를 . ./create-worktree처럼 점(.)을 붙여 실행하는 이유는?
A. 점 없이 실행하면 스크립트가 서브셸에서 돌아,
cd로 바꾼 폴더가 지금 터미널에 반영되지 않습니다. 점이나source를 붙이면 지금 터미널에서 직접 실행되어, 옮긴 폴더가 그대로 유지됩니다.
Q5. 두 작업을 동시에 돌릴 때 머지 컨플릭트를 피하려면?
A. 서로 다른 파일을 고치는 독립적인 이슈를 골라 각각 다른 워크트리에서 작업합니다. 같은 파일의 같은 부분을 동시에 고치면 충돌이 나므로, 그런 작업은 동시에 돌리지 않습니다.
용어집 (이 장에서 새로 나온 말)
| 용어 | 한 줄 뜻 | 일상 비유 |
|---|---|---|
| MVP | 핵심 가치만 담은 최소한의 첫 제품 | 식당 대표 메뉴 3개만 먼저 오픈 |
| Phase | 따로 끝낼 수 있게 자른 작업 묶음 | 이사 단계(방→주방→거실) |
| SPEC.md | 무엇을 어떻게 만들지 적은 명세 파일 | 공사 계획서 |
| 플래닝 모드 | 코드 고치기 전 계획부터 보여 주는 모드 | 요리 전 레시피 확인 |
| lint | 코드 스타일·오류를 자동 검사 | 맞춤법 검사기 |
| typecheck | 값의 종류가 맞는지 검사 | "숫자 칸에 글자?" 잡기 |
| Todo 리스트 | 할 일을 체크박스로 추적 | 장보기 메모 |
| 멀티에이전트 | 터미널 여럿으로 동시에 작업 | 주방 셰프 여러 명 |
| 커스텀 커맨드 | 자주 쓰는 프롬프트를 저장한 단축 명령 | 저장해 둔 자주 쓰는 문구 |
| $ARGUMENT | 입력값이 대신 들어가는 빈칸 | 양식의 "이름: ___" |
| gh | 깃허브를 터미널에서 다루는 공식 도구 | 사이트 안 켜고 이슈 만들기 |
| 이슈 | 할 일·버그를 깃허브에 등록한 메모 | 보드에 붙인 포스트잇 |
| 워크트리 | 한 저장소를 여러 폴더에 펼쳐 동시 작업 | 브랜치별 전용 책상 |
| 브랜치 | 원본 안 건드리고 따로 작업하는 줄기 | 책의 초안 버전 |
| 셸 스크립트 | 명령들을 한 파일에 적어 한 번에 실행 | 매크로 |
| 서브셸 | 잠깐 켰다 꺼지는 별도 터미널 방 | 나가면 한 일이 사라지는 방 |
| 커밋 | 변경을 저장·기록으로 남기기 | 게임 저장하기 |
| PR (풀 리퀘스트) | 합치기 전 검수받는 절차 | 결재 올리기 |
| 머지 | 검수 끝난 변경을 메인에 합치기 | 결재 통과 후 반영 |
| 머지 컨플릭트 | 같은 곳을 다르게 고쳐 생긴 충돌 | 같은 칸에 다른 답 두 개 |
| 블로커 | 먼저 끝나야 하는 선행 작업 | "물 끓이기"가 먼저 |
| 환각 | 없는 사실을 그럴듯하게 지어내는 현상 | 모르면서 아는 척 |
참고 자료
| 자료 | 설명 |
|---|---|
| https://github.com/codefactory-co | 저자(코드팩토리) 깃허브 — 예제 코드 |
| https://docs.github.com/en/pull-requests | 깃허브 풀 리퀘스트 공식 문서 |
| https://git-scm.com/docs/git-worktree | Git 워크트리 공식 문서 |
| https://docs.claude.com | 클로드 코드 공식 문서 |
| https://docs.github.com/en/issues | 깃허브 이슈 공식 문서 |
다음 장 예고: 다음 장에서는 만든 기능을 더 다듬고 운영하는 이야기로 이어집니다. 지금 몰라도 됩니다. 이 장의 흐름(이슈→워크트리→PR→머지)만 손에 익으면 충분합니다.
클릭하거나 Space를 눌러 뒤집기